<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.5"/>
<title>Theron: Theron::YieldStrategy</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
  $(document).ready(function() { searchBox.OnSelectItem(0); });
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td style="padding-left: 0.5em;">
   <div id="projectname">Theron
   &#160;<span id="projectnumber">6.00.02</span>
   </div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.5 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
  <div id="navrow1" class="tabs">
    <ul class="tablist">
      <li><a href="index.html"><span>Main&#160;Page</span></a></li>
      <li><a href="namespaces.html"><span>Namespaces</span></a></li>
      <li><a href="annotated.html"><span>Classes</span></a></li>
      <li><a href="files.html"><span>Files</span></a></li>
      <li>
        <div id="MSearchBox" class="MSearchBoxInactive">
        <span class="left">
          <img id="MSearchSelect" src="search/mag_sel.png"
               onmouseover="return searchBox.OnSearchSelectShow()"
               onmouseout="return searchBox.OnSearchSelectHide()"
               alt=""/>
          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)" 
               onblur="searchBox.OnSearchFieldFocus(false)" 
               onkeyup="searchBox.OnSearchFieldChange(event)"/>
          </span><span class="right">
            <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
          </span>
        </div>
      </li>
    </ul>
  </div>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark">&#160;</span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark">&#160;</span>Classes</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark">&#160;</span>Namespaces</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark">&#160;</span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark">&#160;</span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark">&#160;</span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark">&#160;</span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark">&#160;</span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><span class="SelectionMark">&#160;</span>Enumerator</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(9)"><span class="SelectionMark">&#160;</span>Macros</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(10)"><span class="SelectionMark">&#160;</span>Pages</a></div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div id="nav-path" class="navpath">
  <ul>
<li class="navelem"><a class="el" href="namespaceTheron.html">Theron</a></li>  </ul>
</div>
</div><!-- top -->
<div class="contents">
<table cellspacing="0" cellpadding="0" border="0">
  <tr>
   <td valign="top">
      <div class="navtab">
        <table>
          <tr><td class="navtab"><a class="qindex" href="namespaceTheron_aa1e39ca4c527034d6b784bea7f085e5f.html#aa1e39ca4c527034d6b784bea7f085e5f">int32_t</a></td></tr>
          <tr><td class="navtab"><a class="qindex" href="namespaceTheron_a254da7d1d07833b997828500fbf73daa.html#a254da7d1d07833b997828500fbf73daa">uint32_t</a></td></tr>
          <tr><td class="navtab"><a class="qindex" href="namespaceTheron_ade28202127531a0f27728c157d1b925a.html#ade28202127531a0f27728c157d1b925a">uint64_t</a></td></tr>
          <tr><td class="navtab"><a class="qindex" href="namespaceTheron_acab5b9baa27de520ef83b3024258429c.html#acab5b9baa27de520ef83b3024258429c">uint8_t</a></td></tr>
          <tr><td class="navtab"><a class="qindex" href="namespaceTheron_a529ae0c39c30bf1ddc7fa87de771cbac.html#a529ae0c39c30bf1ddc7fa87de771cbac">uintptr_t</a></td></tr>
          <tr><td class="navtab"><a class="qindex" href="namespaceTheron_a03ee5f87e8369a84dc8f6f922677429c.html#a03ee5f87e8369a84dc8f6f922677429cadb0356601ea051d938311d8ac0d348c5">YIELD_STRATEGY_AGGRESSIVE</a></td></tr>
          <tr><td class="navtab"><a class="qindex" href="namespaceTheron_a03ee5f87e8369a84dc8f6f922677429c.html#a03ee5f87e8369a84dc8f6f922677429ca55078e535ea2f60e6ee9bfd5bc8c894d">YIELD_STRATEGY_BLOCKING</a></td></tr>
          <tr><td class="navtab"><a class="qindex" href="namespaceTheron_a03ee5f87e8369a84dc8f6f922677429c.html#a03ee5f87e8369a84dc8f6f922677429ca6970065a638127538df16540e6515bef">YIELD_STRATEGY_CONDITION</a></td></tr>
          <tr><td class="navtab"><a class="qindex" href="namespaceTheron_a03ee5f87e8369a84dc8f6f922677429c.html#a03ee5f87e8369a84dc8f6f922677429cad34797cf6380cd2b8016d4e7272f8b29">YIELD_STRATEGY_HYBRID</a></td></tr>
          <tr><td class="navtab"><a class="qindex" href="namespaceTheron_a03ee5f87e8369a84dc8f6f922677429c.html#a03ee5f87e8369a84dc8f6f922677429ca20ecfc2067404901e67c734f43f846ff">YIELD_STRATEGY_POLITE</a></td></tr>
          <tr><td class="navtab"><a class="qindex" href="namespaceTheron_a03ee5f87e8369a84dc8f6f922677429c.html#a03ee5f87e8369a84dc8f6f922677429ca542d5ce1884d1dcbd2c45c17bd92bc3b">YIELD_STRATEGY_SPIN</a></td></tr>
          <tr><td class="navtab"><a class="qindex" href="namespaceTheron_a03ee5f87e8369a84dc8f6f922677429c.html#a03ee5f87e8369a84dc8f6f922677429ca40b2a8428fb3f7647e0a0fa55503a084">YIELD_STRATEGY_STRONG</a></td></tr>
          <tr><td class="navtab"><a class="qindexHL" href="namespaceTheron_a03ee5f87e8369a84dc8f6f922677429c.html#a03ee5f87e8369a84dc8f6f922677429c">YieldStrategy</a></td></tr>
        </table>
      </div>
   </td>
   <td valign="top" class="mempage">
<a class="anchor" id="a03ee5f87e8369a84dc8f6f922677429c"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">enum <a class="el" href="namespaceTheron_a03ee5f87e8369a84dc8f6f922677429c.html#a03ee5f87e8369a84dc8f6f922677429c">Theron::YieldStrategy</a></td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Enumerates the available worker thread yield strategies. </p>
<p>Each <a class="el" href="classTheron_1_1Framework.html">Theron::Framework</a> contains a pool of worker threads that are used to execute the actors hosted in the framework. The worker threads service a queue, processing actors that have received messages and executing their registered message handlers.</p>
<p>When constructing a <a class="el" href="classTheron_1_1Framework.html" title="Manager class that hosts, manages, and executes actors. ">Framework</a>, a <a class="el" href="structTheron_1_1Framework_1_1Parameters.html">Theron::Framework::Parameters</a> object may be provided with parameters that control the structure and behavior of the the framework's internal threadpool. This enum defines the available values of the <a class="el" href="structTheron_1_1Framework_1_1Parameters_a7f0d63173a26929b741bd28e0caec82c.html#a7f0d63173a26929b741bd28e0caec82c">mYieldStrategy</a> member of the Parameters structure.</p>
<p>The mYieldStrategy member defines the strategy that the worker threads use to avoid <em>busy</em> <em>waiting</em> on the work queue. The available strategies have different performance characteristics, and are best suited to different kinds of applications.</p>
<p>As of <a class="el" href="namespaceTheron.html" title="Main namespace containing all public API components. ">Theron</a> 6, the default strategy is <a class="el" href="namespaceTheron_a03ee5f87e8369a84dc8f6f922677429c.html#a03ee5f87e8369a84dc8f6f922677429ca6970065a638127538df16540e6515bef">YIELD_STRATEGY_CONDITION</a>. This strategy causes threads to wait on condition variables when no work is available. Waiting on conditions is a traditional approach to scheduling and has the benefit of not consuming CPU cycles when the threads are not busy. Instead, the CPU usage reflects the actual amount of work being done, and unused cycles are available for other applications (or other threads in the system) to use for unrelated work. This feature makes YIELD_STRATEGY_CONDITION a good fit for most applications and the obvious default strategy.</p>
<p>One potential downside of waiting on condition variables is that it involves system calls that can themselves consume thousands of cycles, introducing latency. For that reason, this approach has fallen out of favor in specialized low-latency applications where responding quickly is vital, even at the expense of consuming unused CPU cycles in the process.</p>
<p>This alternative is embodied by YIELD_STRATEGY_SPIN, which causes waiting threads to 'busy-wait' in tight loops, waiting for work queues to become non-empty. The advantage of this approach is that threads are quick to pick up work when it becomes available. The spin loop contains no heavyweight system calls so suffers from little latency. The obvious disadvantage is that the spinning threads consume all available CPU cycles, wasting power and potentially starving other threads (including those in other applications). For that reason YIELD_STRATEGY_SPIN is best used in combination with the use of processor affinity masks (see <a class="el" href="structTheron_1_1Framework_1_1Parameters.html">Framework::Parameters</a>) to limit the execution of the threads to specific cores. Those cores are then effectively dedicated to that purpose.</p>
<p>Finally, YIELD_STRATEGY_HYBRID is a compromise which tries to avoid the rampant consumption of spare CPU cycles caused by busy-waiting, while still avoiding condition variables, by yielding to other threads with a timeout after some period of spinning. The yield calls re-introduce some latency, with the result that this approach lacks the extreme low-latency advantages of YIELD_STRATEGY_SPIN. It also still suffers from the negative that waiting threads will consume all of the available cycles on the cores on which they are run. For that reason it is best used in combination with processor affinity masks, like YIELD_STRATEGY_SPIN. It's advantage over YIELD_STRATEGY_SPIN is that any other threads running on the same cores are less likely to be starved.</p>
<p>When choosing a yield strategy it pays to consider how important low-latency responses are to your application. In most applications latencies of a few milliseconds are not significant, and the default strategy is a reasonable choice. </p>
<table class="fieldtable">
<tr><th colspan="2">Enumerator</th></tr><tr><td class="fieldname"><em><a class="anchor" id="a03ee5f87e8369a84dc8f6f922677429ca6970065a638127538df16540e6515bef"></a>YIELD_STRATEGY_CONDITION</em>&nbsp;</td><td class="fielddoc">
<p>Threads wait on condition variables when no work is available. </p>
</td></tr>
<tr><td class="fieldname"><em><a class="anchor" id="a03ee5f87e8369a84dc8f6f922677429cad34797cf6380cd2b8016d4e7272f8b29"></a>YIELD_STRATEGY_HYBRID</em>&nbsp;</td><td class="fielddoc">
<p>Threads spin for a while, then yield to other threads, when no work is available. </p>
</td></tr>
<tr><td class="fieldname"><em><a class="anchor" id="a03ee5f87e8369a84dc8f6f922677429ca542d5ce1884d1dcbd2c45c17bd92bc3b"></a>YIELD_STRATEGY_SPIN</em>&nbsp;</td><td class="fielddoc">
<p>Threads busy-wait, without yielding, when no work is available. </p>
</td></tr>
<tr><td class="fieldname"><em><a class="anchor" id="a03ee5f87e8369a84dc8f6f922677429ca55078e535ea2f60e6ee9bfd5bc8c894d"></a>YIELD_STRATEGY_BLOCKING</em>&nbsp;</td><td class="fielddoc">
<p>Deprecated - use YIELD_STRATEGY_CONDITION. </p>
</td></tr>
<tr><td class="fieldname"><em><a class="anchor" id="a03ee5f87e8369a84dc8f6f922677429ca20ecfc2067404901e67c734f43f846ff"></a>YIELD_STRATEGY_POLITE</em>&nbsp;</td><td class="fielddoc">
<p>Deprecated - use YIELD_STRATEGY_CONDITION. </p>
</td></tr>
<tr><td class="fieldname"><em><a class="anchor" id="a03ee5f87e8369a84dc8f6f922677429ca40b2a8428fb3f7647e0a0fa55503a084"></a>YIELD_STRATEGY_STRONG</em>&nbsp;</td><td class="fielddoc">
<p>Deprecated - use YIELD_STRATEGY_HYBRID. </p>
</td></tr>
<tr><td class="fieldname"><em><a class="anchor" id="a03ee5f87e8369a84dc8f6f922677429cadb0356601ea051d938311d8ac0d348c5"></a>YIELD_STRATEGY_AGGRESSIVE</em>&nbsp;</td><td class="fielddoc">
<p>Deprecated - use YIELD_STRATEGY_SPIN. </p>
</td></tr>
</table>

</div>
</div>
    </td>
  </tr>
</table>
</div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by &#160;<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.5
</small></address>
</body>
</html>
